<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
 <head>
  <meta http-equiv="content-type" content="text/html; charset=UTF-8">
  <title>Plugin configuration file (&gt;=1.1.x)</title>

 </head>
 <body><div class="manualnavbar" style="text-align: center;">
 <div class="prev" style="text-align: left; float: left;"><a href="mysqlnd-ms.configuration.html">运行时配置</a></div>
 <div class="next" style="text-align: right; float: right;"><a href="mysqlnd-ms.plugin-ini-v1.html">Plugin configuration file (&lt;= 1.0.x)</a></div>
 <div class="up"><a href="mysqlnd-ms.setup.html">安装／配置</a></div>
 <div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="mysqlnd-ms.plugin-ini-json" class="section">
  <h2 class="title">Plugin configuration file (&gt;=1.1.x)</h2>
  <blockquote class="note"><p><strong class="note">Note</strong>: 
   <strong>Changelog: Feature was added in PECL/mysqlnd_ms 1.1.0-beta</strong><br />
   <p class="para">
    The below description applies to PECL/mysqlnd_ms &gt;= 1.1.0-beta.
    It is not valid for prior versions.
   </p>
  </p></blockquote>
  <p class="para">
   The plugin uses its own configuration file. The configuration file
   holds information about the MySQL replication master server,
   the MySQL replication slave servers, the server pick (load balancing) policy,
   the failover strategy, and the use of lazy connections.
  </p>
  <p class="para">
   The plugin loads its configuration file at the beginning of a web request.
   It is then cached in memory and used for the duration of the web request.
   This way, there is no need to restart PHP after deploying the configuration
   file. Configuration file changes will become active almost instantly.
  </p>
  <p class="para">
   The PHP configuration directive
   <a href="mysqlnd-ms.configuration.html#ini.mysqlnd-ms.config-file" class="link"><em>mysqlnd_ms.config_file</em></a>
   is used to set the plugins configuration file. Please note, that
   the PHP configuration directive may not be evaluated for every web request.
   Therefore, changing the plugins configuration file name or location may
   require a PHP restart. However, no restart is required to read changes if
   an already existing plugin configuration file is updated.
  </p>
  <p class="para">
   Using and parsing <acronym title="JavaScript Object Notation">JSON</acronym> is efficient, and using <acronym title="JavaScript Object Notation">JSON</acronym>
   makes it easier to express hierarchical data structures than the standard
   <var class="filename">php.ini</var> format.
  </p>
  <p class="para">
   <div class="example" id="example-1775">
    <p><strong>Example #1 Converting a PHP array (hash) into JSON format</strong></p>
    <div class="example-contents"><p>
     Or alternatively, a developer may be more familiar with the PHP <span class="type"><a href="language.types.array.html" class="type array">array</a></span>
     syntax, and prefer it. This example demonstrates how a developer might convert a
     PHP array to <acronym title="JavaScript Object Notation">JSON</acronym>.
    </p></div>
    <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br />$config&nbsp;</span><span style="color: #007700">=&nbsp;array(<br />&nbsp;&nbsp;</span><span style="color: #DD0000">"myapp"&nbsp;</span><span style="color: #007700">=&gt;&nbsp;array(<br />&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color: #DD0000">"master"&nbsp;</span><span style="color: #007700">=&gt;&nbsp;array(<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color: #DD0000">"master_0"&nbsp;</span><span style="color: #007700">=&gt;&nbsp;array(<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color: #DD0000">"host"&nbsp;&nbsp;&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #DD0000">"localhost"</span><span style="color: #007700">,<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color: #DD0000">"socket"&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #DD0000">"/tmp/mysql.sock"</span><span style="color: #007700">,<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;),<br />&nbsp;&nbsp;&nbsp;&nbsp;),<br />&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color: #DD0000">"slave"&nbsp;</span><span style="color: #007700">=&gt;&nbsp;array(),<br />&nbsp;&nbsp;),<br />);<br /><br /></span><span style="color: #0000BB">file_put_contents</span><span style="color: #007700">(</span><span style="color: #DD0000">"mysqlnd_ms.ini"</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">json_encode</span><span style="color: #007700">(</span><span style="color: #0000BB">$config</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">JSON_PRETTY_PRINT</span><span style="color: #007700">));<br /></span><span style="color: #0000BB">printf</span><span style="color: #007700">(</span><span style="color: #DD0000">"mysqlnd_ms.ini&nbsp;file&nbsp;created...\n"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">printf</span><span style="color: #007700">(</span><span style="color: #DD0000">"Dumping&nbsp;file&nbsp;contents...\n"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">printf</span><span style="color: #007700">(</span><span style="color: #DD0000">"%s\n"</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">str_repeat</span><span style="color: #007700">(</span><span style="color: #DD0000">"-"</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">80</span><span style="color: #007700">));<br />echo&nbsp;</span><span style="color: #0000BB">file_get_contents</span><span style="color: #007700">(</span><span style="color: #DD0000">"mysqlnd_ms.ini"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">printf</span><span style="color: #007700">(</span><span style="color: #DD0000">"\n%s\n"</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">str_repeat</span><span style="color: #007700">(</span><span style="color: #DD0000">"-"</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">80</span><span style="color: #007700">));<br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
    </div>

    <div class="example-contents"><p>以上例程会输出：</p></div>
    <div class="example-contents screen">
<div class="cdata"><pre>
mysqlnd_ms.ini file created...
Dumping file contents...
--------------------------------------------------------------------------------
{
    &quot;myapp&quot;: {
        &quot;master&quot;: {
            &quot;master_0&quot;: {
                &quot;host&quot;: &quot;localhost&quot;,
                &quot;socket&quot;: &quot;\/tmp\/mysql.sock&quot;
            }
        },
        &quot;slave&quot;: [

        ]
    }
}
--------------------------------------------------------------------------------
</pre></div>
    </div>
   </div>
  </p>
  <p class="para">
   A plugin configuration file consists of one or more sections. Sections
   are represented by the top-level object properties of the
   object encoded in the <acronym title="JavaScript Object Notation">JSON</acronym> file. Sections could also
   be called <em class="emphasis">configuration names</em>.
  </p>
  <p class="para">
   Applications reference sections by their name. Applications use section names
   as the host (server) parameter to the various connect methods of the
   <a href="ref.mysqli.html" class="link">mysqli</a>,
   <a href="ref.mysql.html" class="link">mysql</a> and
   <a href="ref.pdo-mysql.html" class="link">PDO_MYSQL</a> extensions. Upon connect,
   the <a href="book.mysqlnd.html" class="link">mysqlnd</a> plugin compares the hostname
   with all of the section names from the plugin configuration file. If the hostname and
   section name match, then the plugin will load the settings for that section.
  </p>
  <p class="para" id="mysqlnd-ms.plugin-ini-json.using-section">
   <div class="example" id="example-1776">
    <p><strong>Example #2 Using section names example</strong></p>
    <div class="example-contents">
<div class="inicode"><pre class="inicode">{
    &quot;myapp&quot;: {
        &quot;master&quot;: {
            &quot;master_0&quot;: {
                &quot;host&quot;: &quot;localhost&quot;
            }
        },
        &quot;slave&quot;: {
            &quot;slave_0&quot;: {
                &quot;host&quot;: &quot;192.168.2.27&quot;
            },
            &quot;slave_1&quot;: {
                &quot;host&quot;: &quot;192.168.2.27&quot;,
                &quot;port&quot;: 3306
            }
        }
    },
    &quot;localhost&quot;: {
        &quot;master&quot;: [
            {
                &quot;host&quot;: &quot;localhost&quot;,
                &quot;socket&quot;: &quot;\/path\/to\/mysql.sock&quot;
            }
        ],
        &quot;slave&quot;: [
            {
                &quot;host&quot;: &quot;192.168.3.24&quot;,
                &quot;port&quot;: &quot;3305&quot;
            },
            {
                &quot;host&quot;: &quot;192.168.3.65&quot;,
                &quot;port&quot;: &quot;3309&quot;
            }
        ]
    }
}</pre>
</div>
    </div>

    <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br /></span><span style="color: #FF8000">/*&nbsp;All&nbsp;of&nbsp;the&nbsp;following&nbsp;connections&nbsp;will&nbsp;be&nbsp;load&nbsp;balanced&nbsp;*/<br /></span><span style="color: #0000BB">$mysqli&nbsp;</span><span style="color: #007700">=&nbsp;new&nbsp;</span><span style="color: #0000BB">mysqli</span><span style="color: #007700">(</span><span style="color: #DD0000">"myapp"</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">"username"</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">"password"</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">"database"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$pdo&nbsp;</span><span style="color: #007700">=&nbsp;new&nbsp;</span><span style="color: #0000BB">PDO</span><span style="color: #007700">(</span><span style="color: #DD0000">'mysql:host=myapp;dbname=database'</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">'username'</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">'password'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$mysql&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">mysql_connect</span><span style="color: #007700">(</span><span style="color: #DD0000">"myapp"</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">"username"</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">"password"</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">$mysqli&nbsp;</span><span style="color: #007700">=&nbsp;new&nbsp;</span><span style="color: #0000BB">mysqli</span><span style="color: #007700">(</span><span style="color: #DD0000">"localhost"</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">"username"</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">"password"</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">"database"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
    </div>

   </div>
  </p>
  <p class="para">
   Section names are strings. It is valid to use a section name such as
   <em>192.168.2.1</em>, <em>127.0.0.1</em> or
   <em>localhost</em>. If, for example, an application
   connects to <em>localhost</em> and a plugin
   configuration section <em>localhost</em> exists, the
   semantics of the connect operation are changed. The application will
   no longer only use the MySQL server running on the host
   <em>localhost</em>, but the plugin will start to load balance
   MySQL queries following the rules from the <em>localhost</em>
   configuration section. This way you can load balance queries from
   an application without changing the applications source code.
   Please keep in mind, that such a configuration may not contribute
   to overall readability of your applications source code. Using section names
   that can be mixed up with host names should be seen as a last resort.
  </p>
  <p class="para" id="mysqlnd-ms.plugin-ini-json.server-list-syntax">
   Each configuration section contains, at a minimum, a list of master servers
   and a list of slave servers. The master list is configured with the keyword
   <em>master</em>, while the slave list is configured with the
   <em>slave</em> keyword. Failing to provide a slave list will result
   in a fatal <strong><code>E_ERROR</code></strong> level error, although a slave list
   may be empty. It is possible to allow no slaves. However, this is only recommended
   with synchronous clusters, please see also
   <a href="mysqlnd-ms.supportedclusters.html" class="link">supported clusters</a>.
   The main part of the documentation focusses on the use
   of asynchronous MySQL replication clusters.
  </p>
  <p class="para">
   The master and slave server lists can be optionally indexed by symbolic
   names for the servers they describe. Alternatively, an array of descriptions
   for slave and master servers may be used.
  </p>
  <p class="para">
   <div class="example" id="example-1777">
    <p><strong>Example #3 List of anonymous slaves</strong></p>
        <div class="example-contents">
<div class="inicode"><pre class="inicode">&quot;slave&quot;: [
    {
        &quot;host&quot;: &quot;192.168.3.24&quot;,
        &quot;port&quot;: &quot;3305&quot;
    },
    {
        &quot;host&quot;: &quot;192.168.3.65&quot;,
        &quot;port&quot;: &quot;3309&quot;
    }
]</pre>
</div>
    </div>

   </div>
  </p>
  <p class="para">
   An anonymous server list is encoded by the <em>JSON array</em> type.
   Optionally, symbolic names may be used for indexing the slave or master servers
   of a server list, and done so using the <em>JSON object</em> type.
  </p>
  <p class="para">
   <div class="example" id="example-1778">
    <p><strong>Example #4 Master list using symbolic names</strong></p>
        <div class="example-contents">
<div class="inicode"><pre class="inicode">&quot;master&quot;: {
    &quot;master_0&quot;: {
        &quot;host&quot;: &quot;localhost&quot;
    }
}</pre>
</div>
    </div>

   </div>
  </p>
  <p class="para">
   It is recommended to index the server lists with symbolic server names.
   The alias names will be shown in error messages.
  </p>
  <p class="para">
   The order of servers is preserved and taken into account by mysqlnd_ms.
   If, for example, you configure round robin load balancing strategy, the
   first <em>SELECT</em> statement will be executed on the
   slave that appears first in the slave server list.
  </p>
  <p class="para">
   A configured server can be described with the <em>host</em>,
   <em>port</em>, <em>socket</em>, <em>db</em>,
   <em>user</em>, <em>password</em> and <em>connect_flags</em>.
   It is mandatory to set the database server host using the <em>host</em>
   keyword. All other settings are optional.
  </p>
  <p class="para">
   <div class="example" id="example-1779">
    <p><strong>Example #5 Keywords to configure a server</strong></p>
    <div class="example-contents">
<div class="inicode"><pre class="inicode">{
    &quot;myapp&quot;: {
        &quot;master&quot;: {
            &quot;master_0&quot;: {
                &quot;host&quot;: &quot;db_server_host&quot;,
                &quot;port&quot;: &quot;db_server_port&quot;,
                &quot;socket&quot;: &quot;db_server_socket&quot;,
                &quot;db&quot;: &quot;database_resp_schema&quot;,
                &quot;user&quot;: &quot;user&quot;,
                &quot;password&quot;: &quot;password&quot;,
                &quot;connect_flags&quot;: 0
            }
        },
        &quot;slave&quot;: {
            &quot;slave_0&quot;: {
                &quot;host&quot;: &quot;db_server_host&quot;,
                &quot;port&quot;: &quot;db_server_port&quot;,
                &quot;socket&quot;: &quot;db_server_socket&quot;
            }
        }
    }
}</pre>
</div>
    </div>

   </div>
  </p>
  <p class="para">
   If a setting is omitted, the plugin will use the value provided by the user
   API call used to open a connection. Please, see the
   <a href="mysqlnd-ms.plugin-ini-json.html#mysqlnd-ms.plugin-ini-json.using-section" class="link">using section names example</a> above.
  </p>
  <p class="para">
   The configuration file format has been changed in version 1.1.0-beta to allow for
   chained filters. Filters are responsible for filtering the configured list of
   servers to identify a server for execution of a given statement.
   Filters are configured with the <em>filter</em> keyword. Filters
   are executed by mysqlnd_ms in the order of their appearance.
   Defining filters is optional. A configuration section in the plugins
   configuration file does not need to have a <em>filters</em> entry.
  </p>
  <p class="para">
   Filters replace the
   <a href="mysqlnd-ms.plugin-ini-v1.html#ini.mysqlnd-ms-plugin-config.pick" class="link"><em>pick[]</em></a>
   setting from prior versions. The new <em>random</em> and
   <em>roundrobin</em> provide the same functionality.
  </p>
  <p class="para">
   <div class="example" id="example-1780">
    <p><strong>Example #6 New <em>roundrobin</em> filter, old functionality</strong></p>
    <div class="example-contents">
<div class="inicode"><pre class="inicode">{
    &quot;myapp&quot;: {
        &quot;master&quot;: {
            &quot;master_0&quot;: {
                &quot;host&quot;: &quot;localhost&quot;
            }
        },
        &quot;slave&quot;: {
            &quot;slave_0&quot;: {
                &quot;host&quot;: &quot;192.168.78.136&quot;,
                &quot;port&quot;: &quot;3306&quot;
            },
            &quot;slave_1&quot;: {
                &quot;host&quot;: &quot;192.168.78.137&quot;,
                &quot;port&quot;: &quot;3306&quot;
            }
        },
        &quot;filters&quot;: {
            &quot;roundrobin&quot;: [

            ]
        }
    }
}</pre>
</div>
    </div>

   </div>
  </p>
  <p class="para">
   The function
   <span class="function"><a href="function.mysqlnd-ms-set-user-pick-server.html" class="function">mysqlnd_ms_set_user_pick_server()</a></span>
   has been removed. Setting a callback is now done with the <em>user</em>
   filter. Some filters accept parameters. The <em>user</em> filter
   requires and accepts a mandatory <em>callback</em> parameter
   to set the callback previously set through the function <span class="function"><a href="function.mysqlnd-ms-set-user-pick-server.html" class="function">mysqlnd_ms_set_user_pick_server()</a></span>.
   <div class="example" id="example-1781">
    <p><strong>Example #7 The <em>user</em> filter replaces <span class="function"><a href="function.mysqlnd-ms-set-user-pick-server.html" class="function">mysqlnd_ms_set_user_pick_server()</a></span></strong></p>
    <div class="example-contents">
<div class="inicode"><pre class="inicode">&quot;filters&quot;: {
    &quot;user&quot;: {
        &quot;callback&quot;: &quot;pick_server&quot;
    }
}</pre>
</div>
    </div>

   </div>
  </p>
  <p class="para" id="mysqlnd-ms.plugin-ini-json.debug_config">
   The validity of the configuration file is checked both when reading the
   configuration file and later when establishing a connection. The configuration
   file is read during PHP request startup. At this early stage a PHP extension
   may not display error messages properly. In the worst case, no error
   is shown and a connection attempt fails without an adequate error message.
   This problem has been cured in version 1.5.0.
  </p>
  <p class="para">
   <div class="example" id="example-1782">
    <p><strong>Example #8 Common error message in case of configuration file issues (upto version 1.5.0)</strong></p>
     <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br />$mysqli&nbsp;</span><span style="color: #007700">=&nbsp;new&nbsp;</span><span style="color: #0000BB">mysqli</span><span style="color: #007700">(</span><span style="color: #DD0000">"myapp"</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">"username"</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">"password"</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">"database"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
    </div>

    <div class="example-contents"><p>以上例程会输出：</p></div>
    <div class="example-contents screen">
<div class="cdata"><pre>
Warning: mysqli::mysqli(): (mysqlnd_ms) (mysqlnd_ms) Failed to parse config file [s1.json]. Please, verify the JSON in Command line code

Warning: mysqli::mysqli(): (HY000/2002): php_network_getaddresses: getaddrinfo failed: Name or service not known in Command line code on line 1

Warning: mysqli::query(): Couldn&#039;t fetch mysqli in Command line code on line 1

Fatal error: Call to a member function fetch_assoc() on a non-object in Command line code on line 1
</pre></div>
    </div>
   </div>
  </p>
  <p class="para">
   Since version 1.5.0 startup errors are additionally buffered and emitted when
   a connection attempt is made. Use the configuration directive
   <a href="mysqlnd-ms.configuration.html#ini.mysqlnd-ms.force-config-usage" class="link"><em>mysqlnd_ms.force_config_usage</em></a>
   to set the error type used to display buffered errors. By default an error
   of type <em>E_WARNING</em> will be emitted.
 </p>
 <p class="para">
   <div class="example" id="example-1783">
    <p><strong>Example #9 Improved configuration file validation since 1.5.0</strong></p>
     <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br />$mysqli&nbsp;</span><span style="color: #007700">=&nbsp;new&nbsp;</span><span style="color: #0000BB">mysqli</span><span style="color: #007700">(</span><span style="color: #DD0000">"myapp"</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">"username"</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">"password"</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">"database"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
    </div>

    <div class="example-contents"><p>以上例程会输出：</p></div>
    <div class="example-contents screen">
<div class="cdata"><pre>
Warning: mysqli::mysqli(): (mysqlnd_ms) (mysqlnd_ms) Failed to parse config file [s1.json]. Please, verify the JSON in Command line code on line 1
</pre></div>
    </div>
   </div>
  </p>
  <p class="para">
   It can be useful to set <a href="mysqlnd-ms.configuration.html#ini.mysqlnd-ms.force-config-usage" class="link"><em>mysqlnd_ms.force_config_usage = 1</em></a>
   when debugging potential configuration file errors. This will not only turn the
   type of buffered startup errors into <em>E_RECOVERABLE_ERROR</em> but also
   help detecting misspelled section names.
  </p>
  <p class="para">
   <div class="example" id="example-1784">
    <p><strong>Example #10 Possibly more precise error due to <em>mysqlnd_ms.force_config_usage=1</em></strong></p>
    <div class="example-contents">
<div class="inicode"><pre class="inicode">mysqlnd_ms.force_config_usage=1</pre>
</div>
    </div>

     <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br />$mysqli&nbsp;</span><span style="color: #007700">=&nbsp;new&nbsp;</span><span style="color: #0000BB">mysqli</span><span style="color: #007700">(</span><span style="color: #DD0000">"invalid_section"</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">"username"</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">"password"</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">"database"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
    </div>

<div class="example-contents"><p>以上例程会输出：</p></div>
    <div class="example-contents screen">
<div class="cdata"><pre>
Warning: mysqli::mysqli(): (mysqlnd_ms) Exclusive usage of configuration enforced but did not find the correct INI file section (invalid_section) in Command line code on line 1 line 1
</pre></div>
    </div>

   </div>
  </p>
  <p class="para">
   Here is a short explanation of the configuration directives that can be used.
  </p>
  <p class="para">
  <dl>

   
     <dt id="ini.mysqlnd-ms-plugin-config-v2.master">
      <em><code class="parameter">master</code></em>
      <span class="type"><span class="type array or object">array or object</span></span>
     </dt>

     <dd>

      <p class="para">
       List of MySQL replication master servers. The list of either
       of the <em>JSON type array</em> to declare an anonymous list
       of servers or of the <em>JSON type object</em>. Please,
       see <a href="mysqlnd-ms.plugin-ini-json.html#mysqlnd-ms.plugin-ini-json.server-list-syntax" class="link">above</a>
       for examples.
      </p>
      <p class="para">
       Setting at least one master server is mandatory. The plugin will issue an
       error of type <em>E_ERROR</em> if the user has failed to
       provide a master server list for a configuration section.
       The fatal error may read
       <em>(mysqlnd_ms) Section [master] doesn&#039;t exist for host
       [name_of_a_config_section] in %s on line %d</em>.
      </p>
      <p class="para">
       A server is described with
       the <em>host</em>, <em>port</em>,
       <em>socket</em>, <em>db</em>,
       <em>user</em>, <em>password</em> and
       <em>connect_flags</em>. It is mandatory to
       provide at  a value for <em>host</em>. If any of the
       other values is not given, it will be taken from the user
       API connect call, please, see also:
       <a href="mysqlnd-ms.plugin-ini-json.html#mysqlnd-ms.plugin-ini-json.using-section" class="link">using section names example</a>.
      </p>
      <p class="para" id="mysqlnd-ms.plugin-ini-json.server-config-keywords">
       Table of server configuration keywords.
      </p>
      <table class="doctable informaltable">
       
        <col width="1*" />
        <col width="7*" />
        <col width="2*" />
        <thead>
         <tr>
          <th>Keyword</th>
          <th>Description</th>
          <th>Version</th>
         </tr>

        </thead>

        <tbody class="tbody">
         <tr>
           <td>
             <em>host</em>
           </td>
           <td>
            <p class="para">
             Database server host. This is a mandatory setting.
             Failing to provide, will cause an error of type <em>E_RECOVERABLE_ERROR</em>
             when the plugin tries to connect to the server. The error message may
             read <em>(mysqlnd_ms) Cannot find [host] in
             [%s] section in config in %s on line %d</em>.
            </p>
          </td>
          <td>Since 1.1.0.</td>
         </tr>

         <tr>
           <td>
             <em>port</em>
           </td>
           <td>
            <p class="para">
              Database server TCP/IP port.
            </p>
          </td>
          <td>Since 1.1.0.</td>
         </tr>

         <tr>
           <td>
             <em>socket</em>
           </td>
           <td>
            <p class="para">
              Database server Unix domain socket.
            </p>
          </td>
          <td>Since 1.1.0.</td>
         </tr>

         <tr>
           <td>
             <em>db</em>
           </td>
           <td>
            <p class="para">
              Database (schemata).
            </p>
          </td>
          <td>Since 1.1.0.</td>
         </tr>

         <tr>
           <td>
             <em>user</em>
           </td>
           <td>
            <p class="para">
              MySQL database user.
            </p>
          </td>
          <td>Since 1.1.0.</td>
         </tr>

         <tr>
           <td>
             <em>password</em>
           </td>
           <td>
            <p class="para">
              MySQL database user password.
            </p>
          </td>
          <td>Since 1.1.0.</td>
         </tr>

         <tr>
           <td>
             <em>connect_flags</em>
           </td>
           <td>
            <p class="para">
              Connection flags.
            </p>
          </td>
          <td>Since 1.1.0.</td>
         </tr>

        </tbody>
       
      </table>

      <p class="para">
       The plugin supports using only one master server. An experimental
       setting exists to enable multi-master support. The details are
       not documented. The setting is meant for development only.
      </p>
     </dd>

    
    
    <dt id="ini.mysqlnd-ms-plugin-config-v2.slave">
      <em><code class="parameter">slave</code></em>
      <span class="type"><span class="type array or object">array or object</span></span>
     </dt>

     <dd>

      <p class="para">
       List of one or more MySQL replication slave servers. The syntax is
       identical to setting master servers, please, see
       <a href="mysqlnd-ms.plugin-ini-json.html#ini.mysqlnd-ms-plugin-config-v2.master" class="link"><em>master</em></a>
       above for details.
      </p>
      <p class="para">
       The plugin supports using one or more slave servers.
      </p>
      <p class="para">
       Setting a list of slave servers is mandatory. The plugin will report
       an error of the type <em>E_ERROR</em> if <em>slave</em>
       is not given for a configuration section. The fatal error message may read
       <em>(mysqlnd_ms) Section [slave] doesn&#039;t exist for host [%s] in %s on line %d</em>.
       Note, that it is valid to use an empty slave server list.
       The error has been introduced to prevent accidently setting no slaves by
       forgetting about the <em>slave</em> setting.
       A master-only setup is still possible using an empty slave server list.
      </p>
      <p class="para">
       If an empty slave list is configured and an attempt is made to
       execute a statement on a slave the plugin may emit a warning like
       <em>mysqlnd_ms) Couldn&#039;t find the appropriate slave connection.
       0 slaves to choose from.</em> upon statement execution.
       It is possible that another warning follows such as
       <em>(mysqlnd_ms) No connection selected by the last filter</em>.
      </p>
     </dd>

    
    
     <dt id="ini.mysqlnd-ms-plugin-config-v2.gtid">
      <em><code class="parameter">global_transaction_id_injection</code></em>
      <span class="type"><span class="type array or object">array or object</span></span>
     </dt>

     <dd>

      <p class="para">
       Global transaction identifier configuration related to both
       the use of the server built-in global transaction ID feature and
       the client-side emulation.
      </p>
      <table class="doctable informaltable">
       
        <col width="1*" />
        <col width="7*" />
        <col width="2*" />
        <thead>
         <tr>
          <th>Keyword</th>
          <th>Description</th>
          <th>Version</th>
         </tr>

        </thead>

        <tbody class="tbody">
         <tr>
          <td>
            <em>fetch_last_gtid</em>
          </td>
          <td>
           <p class="para">
            SQL statement for accessing the latest global transaction identifier.
            The SQL statement is run if the plugin needs to know the most recent
            global transaction identifier. This can be the case, for example, when checking
            MySQL Replication slave status.
            Also used with <span class="function"><a href="function.mysqlnd-ms-get-last-gtid.html" class="function">mysqlnd_ms_get_last_gtid()</a></span>.
           </p>
          </td>
          <td>Since 1.2.0.</td>
         </tr>

         <tr>
          <td>
            <em>check_for_gtid</em>
          </td>
          <td>
           <p class="para">
            SQL statement for checking if a replica has replicated
            all transactions up to and including ones searched for. The
            SQL statement is run when searching for replicas which can offer
            a higher level of consistency than eventual consistency.
            The statement must contain a placeholder <em>#GTID</em>
            which is to be replaced with the global transaction identifier searched
            for by the plugin. Please, check the
            <a href="mysqlnd-ms.quickstart.gtid.html" class="link">quickstart</a> for examples.
           </p>
          </td>
          <td>Since 1.2.0.</td>
         </tr>

         <tr>
          <td>
            <em>report_errors</em>
          </td>
          <td>
           <p class="para">
            Whether to emit an error of type warning if an issue occurs while
            executing any of the configured SQL statements.
           </p>
          </td>
          <td>Since 1.2.0.</td>
         </tr>

         <tr>
          <td>
           <em>on_commit</em>
          </td>
          <td>
           <p class="para">
            Client-side global transaction ID emulation only. SQL statement
            to run when a transaction finished to update the global transaction
            identifier sequence number on the master. Please, see the
            <a href="mysqlnd-ms.quickstart.gtid.html" class="link">quickstart</a> for examples.
           </p>
          </td>
          <td>Since 1.2.0.</td>
          </tr>

          <tr>
          <td>
           <em>wait_for_gtid_timeout</em>
          </td>
          <td>
           <p class="para">
            Instructs the plugin to wait up to <em>wait_for_gtid_timeout</em>
            seconds for a slave to catch up when searching for slaves that can
            deliver session consistency. The setting limits the time spend for
            polling the slave status. If polling the status takes very long, the total
            clock time spend waiting may exceed <em>wait_for_gtid_timeout</em>.
            The plugin calls <em>sleep(1)</em> to sleep one second between
            each two polls.
           </p>
           <p class="para">
            The setting can be used both with the plugins client-side emulation
            and the server-side global transaction identifier feature of MySQL 5.6.
           </p>
           <p class="para">
            Waiting for a slave to replicate a certain GTID needed for session
            consistency also means throttling the client. By throttling the
            client the write load on the master is reduced indirectly. A
            primary copy based replication system, such as MySQL Replication,
            is given more time to reach a consistent state. This can be desired,
            for example, to increase the number of data copies for
            high availability considerations or to prevent the master from being
            overloaded.
           </p>
          </td>
          <td>Since 1.4.0.</td>
          </tr>

         </tbody>
        
       </table>

     </dd>

    
    
     <dt id="ini.mysqlnd-ms-plugin-config-v2.filters">
      <em><code class="parameter">filters</code></em>
      <span class="type"><a href="language.types.object.html" class="type object">object</a></span>
     </dt>

     <dd>

      <p class="para">
       List of filters. A filter is responsible to filter the list of available
       servers for executing a given statement. Filters can be chained.
       The <em>random</em> and <em>roundrobin</em> filter
       replace the
       <a href="mysqlnd-ms.plugin-ini-v1.html#ini.mysqlnd-ms-plugin-config.pick" class="link"><em>pick[]</em></a>
       directive used in prior version to select a load balancing policy.
       The <em>user</em> filter replaces the
       <span class="function"><a href="function.mysqlnd-ms-set-user-pick-server.html" class="function">mysqlnd_ms_set_user_pick_server()</a></span> function.
      </p>
      <p class="para">
       Filters may accept parameters to refine their actions.
      </p>
      <p class="para">
       If no load balancing policy is set, the plugin will default to
       <em>random_once</em>. The <em>random_once</em>
       policy picks a random slave server when running the first read-only
       statement. The slave server will be used for all read-only
       statements until the PHP script execution ends. No load balancing
       policy is set and thus, defaulting takes place,
       if neither the <em>random</em> nor the
       <em>roundrobin</em> are part of a configuration section.
      </p>
      <p class="para">
       If a filter chain is configured so that a filter which output no
       more than once server is used as input for a filter which should be given
       more than one server as input, the plugin may emit a warning upon
       opening a connection. The warning may read: <em>(mysqlnd_ms) Error while creating
       filter &#039;%s&#039; . Non-multi filter &#039;%s&#039; already created.
       Stopping in %s on line %d</em>. Furthermore, an error of
       the error code <em>2000</em>, the sql state <em>HY000</em>
       and an error message similar to the warning may be set on the connection
       handle.
      </p>
      <p class="para">
       <div class="example" id="example-1785">
        <p><strong>Example #11 Invalid filter sequence</strong></p>
        <div class="example-contents">
<div class="inicode"><pre class="inicode">{
    &quot;myapp&quot;: {
        &quot;master&quot;: {
            &quot;master_0&quot;: {
                &quot;host&quot;: &quot;localhost&quot;
            }
        },
        &quot;slave&quot;: {
            &quot;slave_0&quot;: {
                &quot;host&quot;: &quot;192.168.78.136&quot;,
                &quot;port&quot;: &quot;3306&quot;
            }
        },
        &quot;filters&quot;: [
            &quot;roundrobin&quot;,
            &quot;random&quot;
        ]
    }
}</pre>
</div>
         </div>

         <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br />$link&nbsp;</span><span style="color: #007700">=&nbsp;new&nbsp;</span><span style="color: #0000BB">mysqli</span><span style="color: #007700">(</span><span style="color: #DD0000">"myapp"</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">"root"</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">""</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">"test"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">printf</span><span style="color: #007700">(</span><span style="color: #DD0000">"[%d]&nbsp;%s\n"</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">mysqli_connect_errno</span><span style="color: #007700">(),&nbsp;</span><span style="color: #0000BB">mysqli_connect_error</span><span style="color: #007700">());<br /></span><span style="color: #0000BB">$link</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">query</span><span style="color: #007700">(</span><span style="color: #DD0000">"SELECT&nbsp;1&nbsp;FROM&nbsp;DUAL"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
         </div>

         <div class="example-contents"><p>以上例程会输出：</p></div>
        <div class="example-contents screen">
<div class="cdata"><pre>
PHP Warning:  mysqli::mysqli(): (HY000/2000): (mysqlnd_ms) Error while creating filter &#039;random&#039; . Non-multi filter &#039;roundrobin&#039; already created. Stopping in filter_warning.php on line 1
[2000] (mysqlnd_ms) Error while creating filter &#039;random&#039; . Non-multi filter &#039;roundrobin&#039; already created. Stopping
PHP Warning:  mysqli::query(): Couldn&#039;t fetch mysqli in filter_warning.php on line 3
</pre></div>
        </div>
       </div>
      </p>
    </dd>

    
    
     <dt id="ini.mysqlnd-ms-plugin-config-v2.filter-random">
      Filter: <em><code class="parameter">random</code></em>
      <span class="type"><a href="language.types.object.html" class="type object">object</a></span>
     </dt>

     <dd>

      <p class="para">
        The <em>random</em> filter features the random and random once
        load balancing policies, set through the
        <a href="mysqlnd-ms.plugin-ini-v1.html#ini.mysqlnd-ms-plugin-config.pick" class="link"><em>pick[]</em></a>
        directive in older versions.
      </p>
      <p class="para">
        The random policy will pick a random server whenever
        a read-only statement is to be executed. The random once strategy
        picks a random slave server once and continues using the slave for the
        rest of the PHP web request. Random once is a default,
        if load balancing is not configured through a filter.
      </p>
      <p class="para">
       If the <em>random</em> filter is not given any arguments, it
       stands for random load balancing policy.
      </p>
      <p class="para">
       <div class="example" id="example-1786">
        <p><strong>Example #12 Random load balancing with <em>random</em> filter</strong></p>
        <div class="example-contents">
<div class="inicode"><pre class="inicode">{
    &quot;myapp&quot;: {
        &quot;master&quot;: {
            &quot;master_0&quot;: {
                &quot;host&quot;: &quot;localhost&quot;
            }
        },
        &quot;slave&quot;: {
            &quot;slave_0&quot;: {
                &quot;host&quot;: &quot;192.168.78.136&quot;,
                &quot;port&quot;: &quot;3306&quot;
            },
            &quot;slave_1&quot;: {
                &quot;host&quot;: &quot;192.168.78.137&quot;,
                &quot;port&quot;: &quot;3306&quot;
            }
        },
        &quot;filters&quot;: [
            &quot;random&quot;
        ]
    }
}</pre>
</div>
         </div>

       </div>
      </p>
      <p class="para">
       Optionally, the <em>sticky</em> argument can be passed to the
       filter. If the parameter <em>sticky</em> is set to the string
       <em>1</em>, the filter follows the random once
       load balancing strategy.
      </p>
      <p class="para">
       <div class="example" id="example-1787">
        <p><strong>Example #13 Random once load balancing with <em>random</em> filter</strong></p>
        <div class="example-contents">
<div class="inicode"><pre class="inicode">{
    &quot;filters&quot;: {
        &quot;random&quot;: {
            &quot;sticky&quot;: &quot;1&quot;
        }
    }
}</pre>
</div>
        </div>

       </div>
      </p>
      <p class="para">
       Both the <em>random</em> and <em>roundrobin</em>
       filters support setting a priority, a weight for a server, since
       PECL/mysqlnd_ms 1.4.0. If the <em>weight</em> argument is
       passed to the filter, it must assign a weight for all servers. Servers
       must be given an alias name in the <em>slave</em> respectively
       <em>master</em> server lists. The alias must be used
       to reference servers for assigning a priority with <em>weight</em>.
      </p>
      <p class="para">
       <div class="example" id="example-1788">
        <p><strong>Example #14 Referencing error</strong></p>
        <div class="example-contents screen">
<div class="cdata"><pre>
[E_RECOVERABLE_ERROR] mysqli_real_connect(): (mysqlnd_ms) Unknown server &#039;slave3&#039; in &#039;random&#039; filter configuration. Stopping in %s on line %d
</pre></div>
        </div>
       </div>
      </p>
      <p class="para">
       Using a wrong alias name with <em>weight</em> may result in
       an error similar to the shown above.
      </p>
      <p class="para">
       If <em>weight</em> is omitted, the default weight of
       all servers is one.
      </p>
      <p class="para">
       <div class="example" id="example-1789">
        <p><strong>Example #15 Assigning a <em>weight</em> for load balancing</strong></p>
        <div class="example-contents">
<div class="inicode"><pre class="inicode">{
   &quot;myapp&quot;: {
       &quot;master&quot;: {
           &quot;master1&quot;:{
               &quot;host&quot;:&quot;localhost&quot;,
               &quot;socket&quot;:&quot;\/var\/run\/mysql\/mysql.sock&quot;
           }
       },
       &quot;slave&quot;: {
           &quot;slave1&quot;: {
               &quot;host&quot;:&quot;192.168.2.28&quot;,
               &quot;port&quot;:3306
           },
           &quot;slave2&quot;: {
               &quot;host&quot;:&quot;192.168.2.29&quot;,
               &quot;port&quot;:3306
           },
           &quot;slave3&quot;: {
               &quot;host&quot;:&quot;192.0.43.10&quot;,
               &quot;port&quot;:3306
           },
       },
       &quot;filters&quot;: {
           &quot;random&quot;: {
               &quot;weights&quot;: {
                   &quot;slave1&quot;:8,
                   &quot;slave2&quot;:4,
                   &quot;slave3&quot;:1,
                   &quot;master1&quot;:1
               }
           }
       }
   }
}</pre>
</div>
        </div>

       </div>
      </p>
      <p class="para">
       At the average a server assigned a weight of two will be selected twice
       as often as a server assigned a weight of one. Different weights can be
       assigned to reflect differently sized machines, to prefer co-located slaves
       which have a low network latency or, to configure a standby failover server.
       In the latter case, you may want to assign the standby server a very low
       weight in relation to the other servers. For example, given the
       configuration above <em>slave3</em> will get only some eight
       percent of the requests in the average. As long as <em>slave1</em>
       and <em>slave2</em> are running, it will be used sparsely,
       similar to a standby failover server. Upon failure of <em>slave1</em>
       and <em>slave2</em>, the usage of <em>slave3</em>
       increases. Please, check the notes on failover before using
       <em>weight</em> this way.
      </p>
      <p class="para">
       Valid weight values range from 1 to 65535.
      </p>
      <p class="para">
       Unknown arguments are ignored by the filter. No warning or error is given.
      </p>
      <p class="para">
        The filter expects one or more servers as input. Outputs one server.
        A filter sequence such as
        <em>random</em>, <em>roundrobin</em> may
        cause a warning and an error message to be set on the connection
        handle when executing a statement.
      </p>
      <p class="para">
       List of filter arguments.
      </p>
      <table class="doctable informaltable">
       
        <col width="1*" />
        <col width="7*" />
        <col width="2*" />
        <thead>
         <tr>
          <th>Keyword</th>
          <th>Description</th>
          <th>Version</th>
         </tr>

        </thead>

        <tbody class="tbody">
         <tr>
          <td>
            <em>sticky</em>
          </td>
          <td>
           <p class="para">
            Enables or disabled random once load
            balancing policy. See above.
           </p>
          </td>
          <td>Since 1.2.0.</td>
         </tr>

         <tr>
          <td>
            <em>weight</em>
          </td>
          <td>
           <p class="para">
            Assigns a load balancing weight/priority to
            a server. Please, see above for a description.
           </p>
          </td>
          <td>Since 1.4.0.</td>
         </tr>

        </tbody>
       
      </table>

     </dd>

    
    
     <dt id="ini.mysqlnd-ms-plugin-config-v2.filter-roundrobin">
      Filter: <em><code class="parameter">roundrobin</code></em>
      <span class="type"><a href="language.types.object.html" class="type object">object</a></span>
     </dt>

     <dd>

      <p class="para">
       If using the <em>roundrobin</em> filter, the plugin
       iterates over the list of  configured slave servers to pick a server
       for statement execution. If the plugin reaches the end of the list,
       it wraps around to the beginning of the list and picks the first
       configured slave server.
      </p>
      <p class="para">
       <div class="example" id="example-1790">
        <p><strong>Example #16 <em>roundrobin</em> filter</strong></p>
        <div class="example-contents">
<div class="inicode"><pre class="inicode">{
    &quot;myapp&quot;: {
        &quot;master&quot;: {
            &quot;master_0&quot;: {
                &quot;host&quot;: &quot;localhost&quot;
            }
        },
        &quot;slave&quot;: {
            &quot;slave_0&quot;: {
                &quot;host&quot;: &quot;192.168.78.136&quot;,
                &quot;port&quot;: &quot;3306&quot;
            }
        },
        &quot;filters&quot;: [
            &quot;roundrobin&quot;
        ]
    }
}</pre>
</div>
        </div>

       </div>
      </p>
      <p class="para">
        Expects one or more servers as input. Outputs one server.
        A filter sequence such as
        <em>roundrobin</em>, <em>random</em> may
        cause a warning and an error message to be set on the connection
        handle when executing a statement.
      </p>
      <p class="para">
       List of filter arguments.
      </p>
      <table class="doctable informaltable">
       
        <col width="1*" />
        <col width="7*" />
        <col width="2*" />
        <thead>
         <tr>
          <th>Keyword</th>
          <th>Description</th>
          <th>Version</th>
         </tr>

        </thead>

        <tbody class="tbody">
         <tr>
          <td>
            <em>weight</em>
          </td>
          <td>
           <p class="para">
            Assigns a load balancing weight/priority to
            a server. Please, find a description
            <a href="mysqlnd-ms.plugin-ini-json.html#ini.mysqlnd-ms-plugin-config-v2.filter-random" class="link">above</a>.
           </p>
          </td>
          <td>Since 1.4.0.</td>
         </tr>

        </tbody>
       
      </table>

     </dd>

    
    
     <dt id="ini.mysqlnd-ms-plugin-config-v2.filter-user">
      Filter: <em><code class="parameter">user</code></em>
      <span class="type"><a href="language.types.object.html" class="type object">object</a></span>
     </dt>

     <dd>

      <p class="para">
        The <em>user</em> replaces
       <span class="function"><a href="function.mysqlnd-ms-set-user-pick-server.html" class="function">mysqlnd_ms_set_user_pick_server()</a></span> function,
       which was removed in 1.1.0-beta. The filter sets a callback for user-defined
       read/write splitting and server selection.
      </p>
      <p class="para">
        The plugins built-in read/write query split mechanism decisions can be
        overwritten in two ways. The easiest way is to prepend a query string
        with the SQL hints <strong><code>MYSQLND_MS_MASTER_SWITCH</code></strong>,
        <strong><code>MYSQLND_MS_SLAVE_SWITCH</code></strong> or
        <strong><code>MYSQLND_MS_LAST_USED_SWITCH</code></strong>. Using SQL hints one can
        control, for example, whether a query shall be send to the MySQL replication
        master server or one of the slave servers. By help of SQL hints it is
        not possible to pick a certain slave server for query execution.
      </p>
      <p class="para">
       Full control on server selection can be gained using a callback function.
       Use of a callback is recommended to expert users only because the callback
       has to cover all cases otherwise handled by the plugin.
      </p>
      <p class="para">
       The plugin will invoke the callback function for selecting a server from the
       lists of configured master and slave servers. The callback function
       inspects the query to run and picks a server for query execution by returning
       the hosts URI, as found in the master and slave list.
      </p>
      <p class="para">
       If the lazy connections are enabled and the callback chooses a slave server for
       which no connection has been established so far and establishing the connection
       to the slave fails, the plugin will return an error upon the next action
       on the failed connection, for example, when running a query. It is the
       responsibility of the application developer to handle the error. For example,
       the application can re-run the query to trigger a new server selection and
       callback invocation. If so, the callback must make sure to select
       a different slave, or check slave availability, before returning to
       the plugin to prevent an endless loop.
      </p>
      <p class="para">
       <div class="example" id="example-1791">
        <p><strong>Example #17 Setting a callback</strong></p>
        <div class="example-contents">
<div class="inicode"><pre class="inicode">{
    &quot;myapp&quot;: {
        &quot;master&quot;: {
            &quot;master_0&quot;: {
                &quot;host&quot;: &quot;localhost&quot;
            }
        },
        &quot;slave&quot;: {
            &quot;slave_0&quot;: {
                &quot;host&quot;: &quot;192.168.78.136&quot;,
                &quot;port&quot;: &quot;3306&quot;
            }
        },
        &quot;filters&quot;: {
            &quot;user&quot;: {
                &quot;callback&quot;: &quot;pick_server&quot;
            }
        }
    }
}</pre>
</div>
         </div>

       </div>
      </p>
      <p class="para">
       The callback is supposed to return a host to run the query on.
       The host URI is to be taken from the master and slave connection lists
       passed to the callback function. If callback returns a value neither
       found in the master nor in the slave connection lists the plugin
       will emit an error of the type <em>E_RECOVERABLE_ERROR</em>
       The error may read like
       <em>  (mysqlnd_ms) User filter callback has returned an unknown server.
       The server &#039;server that is not in master or slave list&#039; can neither be found
       in the master list nor in the slave list</em>.
       If the application catches the error to ignore it, follow up errors
       may be set on the connection handle, for example,
       <em>(mysqlnd_ms) No connection selected by the last filter</em> with
       the error code <em>2000</em> and the sqlstate <em>HY000</em>.
       Furthermore a warning may be emitted.
      </p>
      <p class="para">
       Referencing a non-existing function as a callback will result
       in any error of the type <em>E_RECOVERABLE_ERROR</em> whenever
       the plugin tries to callback function. The error message may reads like:
       <em>(mysqlnd_ms) Specified callback (pick_server) is
       not a valid callback</em>. If the application catches the error to
       ignore it, follow up errors may be set on the connection handle, for example,
       <em>(mysqlnd_ms) Specified callback (pick_server) is
       not a valid callback</em> with the error code <em>2000</em>
       and the sqlstate <em>HY000</em>. Furthermore a warning
       may be emitted.
      </p>
      <p class="para">
       The following parameters are passed from the plugin to the callback.
      </p>
      <table class="doctable informaltable">
       
        <col width="1*" />
        <col width="7*" />
        <col width="2*" />
        <thead>
         <tr>
          <th>Parameter</th>
          <th>Description</th>
          <th>Version</th>
         </tr>

        </thead>

        <tbody class="tbody">
         <tr>
           <td>
             <em>connected_host</em>
           </td>
           <td>
            <p class="para">
             URI of the currently connected database server.
            </p>
          </td>
          <td>Since 1.1.0.</td>
         </tr>

         <tr>
           <td>
             <em>query</em>
           </td>
           <td>
            <p class="para">
             Query string of the statement for which a server needs
             to be picked.
            </p>
          </td>
          <td>Since 1.1.0.</td>
         </tr>

         <tr>
           <td>
             <em>masters</em>
           </td>
           <td>
            <p class="para">
             List of master servers to choose from. Note, that the list of master
             servers may not be identical to the list of configured master
             servers if the filter is not the first in the filter chain.
             Previously run filters may have reduced the master
             list already.
            </p>
          </td>
          <td>Since 1.1.0.</td>
         </tr>

         <tr>
           <td>
             <em>slaves</em>
           </td>
           <td>
            <p class="para">
             List of slave servers to choose from. Note, that the list of master
             servers may not be identical to the list of configured master
             servers if the filter is not the first in the filter chain.
             Previously run filters may have reduced the master
             list already.
            </p>
          </td>
          <td>Since 1.1.0.</td>
         </tr>

         <tr>
           <td>
             <em>last_used_connection</em>
           </td>
           <td>
            <p class="para">
              URI of the server of the connection used to execute the previous
              statement on.
            </p>
          </td>
          <td>Since 1.1.0.</td>
         </tr>

         <tr>
           <td>
             <em>in_transaction</em>
           </td>
           <td>
            <p class="para">
             Boolean flag indicating whether the statement is
             part of an open transaction. If autocommit mode is turned
             off, this will be set to <strong><code>TRUE</code></strong>. Otherwise
             it is set to <strong><code>FALSE</code></strong>.
            </p>
            <p class="para">
             Transaction detection is based on monitoring the
             mysqlnd library call <em>set_autocommit</em>.
             Monitoring is not possible before PHP 5.4.0. Please, see
             <a href="mysqlnd-ms.pooling.html" class="link">connection pooling and switching</a>
             concepts discussion for further details.
            </p>
          </td>
          <td>Since 1.1.0.</td>
         </tr>

        </tbody>
       
      </table>

     <p class="para">
      <div class="example" id="example-1792">
        <p><strong>Example #18 Using a callback</strong></p>
        <div class="example-contents">
<div class="inicode"><pre class="inicode">{
    &quot;myapp&quot;: {
        &quot;master&quot;: {
            &quot;master_0&quot;: {
                &quot;host&quot;: &quot;localhost&quot;
            }
        },
        &quot;slave&quot;: {
            &quot;slave_0&quot;: {
                &quot;host&quot;: &quot;192.168.2.27&quot;,
                &quot;port&quot;: &quot;3306&quot;
            },
            &quot;slave_1&quot;: {
                &quot;host&quot;: &quot;192.168.78.136&quot;,
                &quot;port&quot;: &quot;3306&quot;
            }
        },
        &quot;filters&quot;: {
            &quot;user&quot;: {
                &quot;callback&quot;: &quot;pick_server&quot;
            }
        }
    }
}</pre>
</div>
         </div>

         <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br /></span><span style="color: #007700">function&nbsp;</span><span style="color: #0000BB">pick_server</span><span style="color: #007700">(</span><span style="color: #0000BB">$connected</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$query</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$masters</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$slaves</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$last_used_connection</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$in_transaction</span><span style="color: #007700">)<br />{<br />&nbsp;static&nbsp;</span><span style="color: #0000BB">$slave_idx&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">0</span><span style="color: #007700">;<br />&nbsp;static&nbsp;</span><span style="color: #0000BB">$num_slaves&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">NULL</span><span style="color: #007700">;<br />&nbsp;if&nbsp;(</span><span style="color: #0000BB">is_null</span><span style="color: #007700">(</span><span style="color: #0000BB">$num_slaves</span><span style="color: #007700">))<br />&nbsp;&nbsp;</span><span style="color: #0000BB">$num_slaves&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">count</span><span style="color: #007700">(</span><span style="color: #0000BB">$slaves</span><span style="color: #007700">);<br /><br />&nbsp;</span><span style="color: #FF8000">/*&nbsp;default:&nbsp;fallback&nbsp;to&nbsp;the&nbsp;plugins&nbsp;build-in&nbsp;logic&nbsp;*/<br />&nbsp;</span><span style="color: #0000BB">$ret&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">NULL</span><span style="color: #007700">;<br /><br />&nbsp;</span><span style="color: #0000BB">printf</span><span style="color: #007700">(</span><span style="color: #DD0000">"User&nbsp;has&nbsp;connected&nbsp;to&nbsp;'%s'...\n"</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$connected</span><span style="color: #007700">);<br />&nbsp;</span><span style="color: #0000BB">printf</span><span style="color: #007700">(</span><span style="color: #DD0000">"...&nbsp;deciding&nbsp;where&nbsp;to&nbsp;run&nbsp;'%s'\n"</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$query</span><span style="color: #007700">);<br /><br />&nbsp;</span><span style="color: #0000BB">$where&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">mysqlnd_ms_query_is_select</span><span style="color: #007700">(</span><span style="color: #0000BB">$query</span><span style="color: #007700">);<br />&nbsp;switch&nbsp;(</span><span style="color: #0000BB">$where</span><span style="color: #007700">)<br />&nbsp;{<br />&nbsp;&nbsp;case&nbsp;</span><span style="color: #0000BB">MYSQLND_MS_QUERY_USE_MASTER</span><span style="color: #007700">:<br />&nbsp;&nbsp;&nbsp;</span><span style="color: #0000BB">printf</span><span style="color: #007700">(</span><span style="color: #DD0000">"...&nbsp;using&nbsp;master\n"</span><span style="color: #007700">);<br />&nbsp;&nbsp;&nbsp;</span><span style="color: #0000BB">$ret&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">$masters</span><span style="color: #007700">[</span><span style="color: #0000BB">0</span><span style="color: #007700">];<br />&nbsp;&nbsp;&nbsp;break;<br />&nbsp;&nbsp;case&nbsp;</span><span style="color: #0000BB">MYSQLND_MS_QUERY_USE_SLAVE</span><span style="color: #007700">:<br />&nbsp;&nbsp;&nbsp;</span><span style="color: #FF8000">/*&nbsp;SELECT&nbsp;or&nbsp;SQL&nbsp;hint&nbsp;for&nbsp;using&nbsp;slave&nbsp;*/<br />&nbsp;&nbsp;&nbsp;</span><span style="color: #007700">if&nbsp;(</span><span style="color: #0000BB">stristr</span><span style="color: #007700">(</span><span style="color: #0000BB">$query</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">"FROM&nbsp;table_on_slave_a_only"</span><span style="color: #007700">))<br />&nbsp;&nbsp;&nbsp;{<br />&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color: #FF8000">/*&nbsp;a&nbsp;table&nbsp;which&nbsp;is&nbsp;only&nbsp;on&nbsp;the&nbsp;first&nbsp;configured&nbsp;slave&nbsp;&nbsp;*/<br />&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color: #0000BB">printf</span><span style="color: #007700">(</span><span style="color: #DD0000">"...&nbsp;access&nbsp;to&nbsp;table&nbsp;available&nbsp;only&nbsp;on&nbsp;slave&nbsp;A&nbsp;detected\n"</span><span style="color: #007700">);<br />&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color: #0000BB">$ret&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">$slaves</span><span style="color: #007700">[</span><span style="color: #0000BB">0</span><span style="color: #007700">];<br />&nbsp;&nbsp;&nbsp;}<br />&nbsp;&nbsp;&nbsp;else<br />&nbsp;&nbsp;&nbsp;{<br />&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color: #FF8000">/*&nbsp;round&nbsp;robin&nbsp;*/<br />&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color: #0000BB">printf</span><span style="color: #007700">(</span><span style="color: #DD0000">"...&nbsp;some&nbsp;read-only&nbsp;query&nbsp;for&nbsp;a&nbsp;slave\n"</span><span style="color: #007700">);<br />&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color: #0000BB">$ret&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">$slaves</span><span style="color: #007700">[</span><span style="color: #0000BB">$slave_idx</span><span style="color: #007700">++&nbsp;%&nbsp;</span><span style="color: #0000BB">$num_slaves</span><span style="color: #007700">];<br />&nbsp;&nbsp;&nbsp;}<br />&nbsp;&nbsp;&nbsp;break;<br />&nbsp;&nbsp;case&nbsp;</span><span style="color: #0000BB">MYSQLND_MS_QUERY_LAST_USED</span><span style="color: #007700">:<br />&nbsp;&nbsp;&nbsp;</span><span style="color: #0000BB">printf</span><span style="color: #007700">(</span><span style="color: #DD0000">"...&nbsp;using&nbsp;last&nbsp;used&nbsp;server\n"</span><span style="color: #007700">);<br />&nbsp;&nbsp;&nbsp;</span><span style="color: #0000BB">$ret&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">$last_used_connection</span><span style="color: #007700">;<br />&nbsp;&nbsp;&nbsp;break;<br />&nbsp;}<br /><br />&nbsp;</span><span style="color: #0000BB">printf</span><span style="color: #007700">(</span><span style="color: #DD0000">"...&nbsp;ret&nbsp;=&nbsp;'%s'\n"</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$ret</span><span style="color: #007700">);<br />&nbsp;return&nbsp;</span><span style="color: #0000BB">$ret</span><span style="color: #007700">;<br />}<br /><br /></span><span style="color: #0000BB">$mysqli&nbsp;</span><span style="color: #007700">=&nbsp;new&nbsp;</span><span style="color: #0000BB">mysqli</span><span style="color: #007700">(</span><span style="color: #DD0000">"myapp"</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">"root"</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">""</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">"test"</span><span style="color: #007700">);<br /><br />if&nbsp;(!(</span><span style="color: #0000BB">$res&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">query</span><span style="color: #007700">(</span><span style="color: #DD0000">"SELECT&nbsp;1&nbsp;FROM&nbsp;DUAL"</span><span style="color: #007700">)))<br />&nbsp;</span><span style="color: #0000BB">printf</span><span style="color: #007700">(</span><span style="color: #DD0000">"[%d]&nbsp;%s\n"</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">errno</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">error</span><span style="color: #007700">);<br />else<br />&nbsp;</span><span style="color: #0000BB">$res</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">close</span><span style="color: #007700">();<br /><br />if&nbsp;(!(</span><span style="color: #0000BB">$res&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">query</span><span style="color: #007700">(</span><span style="color: #DD0000">"SELECT&nbsp;2&nbsp;FROM&nbsp;DUAL"</span><span style="color: #007700">)))<br />&nbsp;</span><span style="color: #0000BB">printf</span><span style="color: #007700">(</span><span style="color: #DD0000">"[%d]&nbsp;%s\n"</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">errno</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">error</span><span style="color: #007700">);<br />else<br />&nbsp;</span><span style="color: #0000BB">$res</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">close</span><span style="color: #007700">();<br /><br /><br />if&nbsp;(!(</span><span style="color: #0000BB">$res&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">query</span><span style="color: #007700">(</span><span style="color: #DD0000">"SELECT&nbsp;*&nbsp;FROM&nbsp;table_on_slave_a_only"</span><span style="color: #007700">)))<br />&nbsp;</span><span style="color: #0000BB">printf</span><span style="color: #007700">(</span><span style="color: #DD0000">"[%d]&nbsp;%s\n"</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">errno</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">error</span><span style="color: #007700">);<br />else<br />&nbsp;</span><span style="color: #0000BB">$res</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">close</span><span style="color: #007700">();<br /><br /></span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">close</span><span style="color: #007700">();<br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
         </div>

         <div class="example-contents"><p>以上例程会输出：</p></div>
         <div class="example-contents screen">
<div class="cdata"><pre>
User has connected to &#039;myapp&#039;...
... deciding where to run &#039;SELECT 1 FROM DUAL&#039;
... some read-only query for a slave
... ret = &#039;tcp://192.168.2.27:3306&#039;
User has connected to &#039;myapp&#039;...
... deciding where to run &#039;SELECT 2 FROM DUAL&#039;
... some read-only query for a slave
... ret = &#039;tcp://192.168.78.136:3306&#039;
User has connected to &#039;myapp&#039;...
... deciding where to run &#039;SELECT * FROM table_on_slave_a_only&#039;
... access to table available only on slave A detected
... ret = &#039;tcp://192.168.2.27:3306&#039;
</pre></div>
         </div>
       </div>
      </p>
     </dd>

    
    
     <dt id="ini.mysqlnd-ms-plugin-config-v2.filter-user-multi">
      Filter: <em><code class="parameter">user_multi</code></em>
      <span class="type"><a href="language.types.object.html" class="type object">object</a></span>
     </dt>

     <dd>

      <p class="para">
       The <em>user_multi</em> differs from the <em>user</em>
       only in one aspect. Otherwise, their syntax is identical.
       The <em>user</em> filter must pick
       and return exactly one node for statement execution. A filter chain
       usually ends with a filter that emits only one node. The filter chain
       shall reduce the list of candidates for statement execution down to
       one. This, only one node left, is the case after the <em>user</em>
       filter has been run.
      </p>
      <p class="para">
       The <em>user_multi</em> filter is a multi filter. It returns a
       list of slave and a list of master servers. This list needs further filtering
       to identify exactly one node for statement execution. A multi filter is typically
       placed at the top of the filter chain. The <em>quality_of_service</em>
       filter is another example of a multi filter.
      </p>
      <p class="para">
       The return value of the callback set for <em>user_multi</em> must
       be an an array with two elements. The first element holds a list of selected master
       servers. The second element contains a list of selected slave servers. The
       lists shall contain the keys of the slave and master servers as found in
       the slave and master lists passed to the callback. The below example returns
       random master and slave lists extracted from the functions input.
      </p>
      <p class="para">
      <div class="example" id="example-1793">
        <p><strong>Example #19 Returning random masters and slaves</strong></p>
        <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br /></span><span style="color: #007700">function&nbsp;</span><span style="color: #0000BB">pick_server</span><span style="color: #007700">(</span><span style="color: #0000BB">$connected</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$query</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$masters</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$slaves</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$last_used_connection</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$in_transaction</span><span style="color: #007700">)<br />{<br />&nbsp;&nbsp;</span><span style="color: #0000BB">$picked_masters&nbsp;</span><span style="color: #007700">=&nbsp;array()<br />&nbsp;&nbsp;foreach&nbsp;(</span><span style="color: #0000BB">$masters&nbsp;</span><span style="color: #007700">as&nbsp;</span><span style="color: #0000BB">$key&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #0000BB">$value</span><span style="color: #007700">)&nbsp;{<br />&nbsp;&nbsp;&nbsp;&nbsp;if&nbsp;(</span><span style="color: #0000BB">mt_rand</span><span style="color: #007700">(</span><span style="color: #0000BB">0</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">2</span><span style="color: #007700">)&nbsp;&gt;&nbsp;</span><span style="color: #0000BB">1</span><span style="color: #007700">)<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color: #0000BB">$picked_masters</span><span style="color: #007700">[]&nbsp;=&nbsp;</span><span style="color: #0000BB">$key</span><span style="color: #007700">;<br />&nbsp;&nbsp;}<br />&nbsp;&nbsp;</span><span style="color: #0000BB">$picked_slaves&nbsp;</span><span style="color: #007700">=&nbsp;array()<br />&nbsp;&nbsp;foreach&nbsp;(</span><span style="color: #0000BB">$slaves&nbsp;</span><span style="color: #007700">as&nbsp;</span><span style="color: #0000BB">$key&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #0000BB">$value</span><span style="color: #007700">)&nbsp;{<br />&nbsp;&nbsp;&nbsp;&nbsp;if&nbsp;(</span><span style="color: #0000BB">mt_rand</span><span style="color: #007700">(</span><span style="color: #0000BB">0</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">2</span><span style="color: #007700">)&nbsp;&gt;&nbsp;</span><span style="color: #0000BB">1</span><span style="color: #007700">)<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color: #0000BB">$picked_slaves</span><span style="color: #007700">[]&nbsp;=&nbsp;</span><span style="color: #0000BB">$key</span><span style="color: #007700">;<br />&nbsp;&nbsp;}<br />&nbsp;&nbsp;return&nbsp;array(</span><span style="color: #0000BB">$picked_masters</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$picked_slaves</span><span style="color: #007700">);<br />}<br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
         </div>

       </div>
      </p>
      <p class="para">
       The plugin will issue an
       error of type <em>E_RECOVERABLE</em> if the callback fails to return
       a server list. The error may read <em>(mysqlnd_ms) User multi
       filter callback has not returned a list of servers to use.
       The callback must return an array in %s on line %d</em>. In case the
       server list is not empty but has invalid servers key/ids in it, an error
       of type <em>E_RECOVERABLE</em> will the thrown with an
       error message like <em>(mysqlnd_ms) User multi filter callback
       has returned an invalid list of servers to use.
       Server id is negative in %s on line %d</em>, or similar.
      </p>
      <p class="para">
       Whether an error is emitted in case of an empty slave or master list
       depends on the configuration. If an empty master list is returned
       for a write operation, it is likely that the plugin will emit a
       warning that may read <em>(mysqlnd_ms) Couldn&#039;t find the appropriate
       master connection. 0 masters to choose from. Something is wrong in %s on line %d</em>.
       Typically a follow up error of type <em>E_ERROR</em> will happen.
       In case of a read operation and an empty slave list the behavior depends
       on the fail over configuration. If fail over to master is enabled, no
       error should appear. If fail over to master is deactivated the plugin will
       emit a warning that may read <em>(mysqlnd_ms) Couldn&#039;t find the appropriate
       slave connection. 0 slaves to choose from. Something is wrong in %s on line %d</em>.
      </p>
     </dd>

    


    
     <dt id="ini.mysqlnd-ms-plugin-config-v2.filter-node-groups">
      Filter: <em><code class="parameter">node_groups</code></em>
      <span class="type"><a href="language.types.object.html" class="type object">object</a></span>
     </dt>

     <dd>

      <p class="para">
       The <em>node_groups</em> filter lets you group cluster nodes
       and query selected groups, for example, to support data partitioning.
       Data partitioning can be required for manual sharding, primary copy based
       clusters running multiple masters, or to avoid hot spots in update everywhere
       clusters that have no built-in partitioning. The filter is a multi filter
       which returns zero, one or multiple of its input servers. Thus, it
       must be followed by other filters to reduce the number of candidates
       down to one for statement execution.
      </p>
       <table class="doctable informaltable">
       
        <col width="1*" />
        <col width="7*" />
        <col width="2*" />
        <thead>
         <tr>
          <th>Keyword</th>
          <th>Description</th>
          <th>Version</th>
         </tr>

        </thead>

        <tbody class="tbody">
         <tr>
           <td>
             <em>user defined node group name</em>
           </td>
           <td>
            <p class="para">
             One or more node groups must be defined. A node group can have an
             arbitrary user defined name. The name is used in combination with
             a SQL hint to restrict query execution to the nodes listed for the
             node group. To run a query on any of the servers of a node group,
             the query must begin with the SQL hint
             <em>/*user defined node group name*/</em>.
             Please note, no white space is allowed around
             <em>user defined node group name</em>. Because
             <em>user defined node group name</em> is used as-is
             as part of a SQL hint, you should choose the name that is compliant
             with the SQL language.
            </p>
            <p class="para">
             Each node group entry must contain a list of <em>master</em>
             servers. Additional <em>slave</em> servers are allowed.
             Failing to provide a list of <em>master</em> for a node group
             <em>name_of_group</em> may cause an
             error of type <strong><code>E_RECOVERABLE_ERROR</code></strong> like
             <em>(mysqlnd_ms) No masters configured in node group &#039;name_of_group&#039; for &#039;node_groups&#039; filter</em>.
            </p>
            <p class="para">
             The list of master and slave servers must reference corresponding
             entries in the
             <a href="mysqlnd-ms.plugin-ini-json.html#ini.mysqlnd-ms-plugin-config-v2.master" class="link">global master</a>
             respectively <a href="mysqlnd-ms.plugin-ini-json.html#ini.mysqlnd-ms-plugin-config-v2.slave" class="link">slave</a>
             server list. Referencing an unknown server in either of the both server
             lists may cause an <strong><code>E_RECOVERABLE_ERROR</code></strong> error like
             <em>(mysqlnd_ms) Unknown master &#039;server_alias_name&#039; (section &#039;name_of_group&#039;) in &#039;node_groups&#039; filter configuration</em>.
            </p>
            <p class="para">
             <div class="example" id="example-1794">
               <p><strong>Example #20 Manual partitioning</strong></p>
                <div class="example-contents">
<div class="inicode"><pre class="inicode">{
  &quot;myapp&quot;: {
       &quot;master&quot;: {
            &quot;master_0&quot;: {
                &quot;host&quot;: &quot;localhost&quot;,
                &quot;socket&quot;: &quot;\/tmp\/mysql.sock&quot;
            }
        },
        &quot;slave&quot;: {
            &quot;slave_0&quot;: {
                &quot;host&quot;: &quot;192.168.2.28&quot;,
                &quot;port&quot;: 3306
            },
            &quot;slave_1&quot;: {
                &quot;host&quot;: &quot;127.0.0.1&quot;,
                &quot;port&quot;: 3311
            }
        },
        &quot;filters&quot;: {
            &quot;node_groups&quot;: {
                &quot;Partition_A&quot; : {
                    &quot;master&quot;: [&quot;master_0&quot;],
                    &quot;slave&quot;: [&quot;slave_0&quot;]
                }
            },
           &quot;roundrobin&quot;: []
        }
    }
}</pre>
</div>
              </div>

             </div>
            </p>
            <p class="para">
              Please note, if a filter chain
              generates an empty slave list and the PHP configuration directive
              <em>mysqlnd_ms.multi_master=0</em> is used, the plugin may
              emit a warning.
            </p>
          </td>
          <td>Since 1.5.0.</td>
         </tr>

        </tbody>
       
      </table>

     </dd>

    

    
     <dt id="ini.mysqlnd-ms-plugin-config-v2.filter-qos">
      Filter: <em><code class="parameter">quality_of_service</code></em>
      <span class="type"><a href="language.types.object.html" class="type object">object</a></span>
     </dt>

     <dd>

      <p class="para">
       The <em>quality_of_service</em> identifies cluster nodes
       capable of delivering a certain quality of service. It is a multi filter
       which returns zero, one or multiple of its input servers. Thus, it
       must be followed by other filters to reduce the number of candidates
       down to one for statement execution.
      </p>
      <p class="para">
       The <em>quality_of_service</em> filter has been introduced in 1.2.0-alpha.
       In the 1.2 series the filters focus is on the consistency aspect of
       service quality. Different types of clusters offer different
       default data consistencies. For example, an asynchronous MySQL
       replication slave offers eventual consistency. The slave may not
       be able to deliver requested data because it has not replicated the write,
       it may serve stale database because its lagging behind or it may serve
       current information. Often, this is acceptable. In some cases
       higher consistency levels are needed for the application to work correct.
       In those cases, the <em>quality_of_service</em> can filter out cluster nodes
       which cannot deliver the necessary quality of service.
      </p>
      <p class="para">
       The <em>quality_of_service</em> filter can be replaced or created
       at runtime. A successful call to
       <span class="function"><a href="function.mysqlnd-ms-set-qos.html" class="function">mysqlnd_ms_set_qos()</a></span>
       removes all existing <em>qos</em> filter entries from the
       filter list and installs a new one at the very beginning. All settings
       that can be made through
       <span class="function"><a href="function.mysqlnd-ms-set-qos.html" class="function">mysqlnd_ms_set_qos()</a></span>
       can also be in the plugins configuration file. However, use of the function
       is by far the most common use case. Instead of setting session consistency and
       strong consistency service levels in the plugins configuration file it is
       recommended to define only masters and no slaves. Both service levels will
       force the use of masters only. Using an empty slave list shortens the
       configuration file, thus improving readability. The only service level for which
       there is a case of defining in the plugins configuration file is the combination
       of eventual consistency and maximum slave lag.
      </p>
      <table class="doctable informaltable">
       
        <col width="1*" />
        <col width="7*" />
        <col width="2*" />
        <thead>
         <tr>
          <th>Keyword</th>
          <th>Description</th>
          <th>Version</th>
         </tr>

        </thead>

        <tbody class="tbody">
         <tr>
           <td>
             <em>eventual_consistency</em>
           </td>
           <td>
            <p class="para">
             Request eventual consistency. Allows the use of all
             master and slave servers. Data returned may or may not be current.
            </p>
            <p class="para">
             Eventual consistency accepts an optional <em>age</em>
             parameter. If <em>age</em> is given the plugin considers
             only slaves for reading for which MySQL replication reports
             a slave lag less or equal to <em>age</em>.
             The replication lag is measure using <em>SHOW SLAVE STATUS</em>.
             If the plugin fails to fetch the replication lag, the slave tested
             is skipped. Implementation details and tips are given in the
             <a href="mysqlnd-ms.qos-consistency.html" class="link">quality of service concepts section</a>.
            </p>
            <p class="para">
              Please note, if a filter chain
              generates an empty slave list and the PHP configuration directive
              <em>mysqlnd_ms.multi_master=0</em> is used, the plugin may
              emit a warning.
            </p>
            <p class="para">
             <div class="example" id="example-1795">
               <p><strong>Example #21 Global limit on slave lag</strong></p>
                <div class="example-contents">
<div class="inicode"><pre class="inicode">{
    &quot;myapp&quot;: {
        &quot;master&quot;: {
            &quot;master_0&quot;: {
                &quot;host&quot;: &quot;localhost&quot;
            }
        },
        &quot;slave&quot;: {
            &quot;slave_0&quot;: {
                &quot;host&quot;: &quot;192.168.2.27&quot;,
                &quot;port&quot;: &quot;3306&quot;
            },
            &quot;slave_1&quot;: {
                &quot;host&quot;: &quot;192.168.78.136&quot;,
                &quot;port&quot;: &quot;3306&quot;
            }
        },
        &quot;filters&quot;: {
            &quot;quality_of_service&quot;: {
                &quot;eventual_consistency&quot;: {
                    &quot;age&quot;:123
                }
            }
        }
    }
}</pre>
</div>
              </div>

             </div>
            </p>
          </td>
          <td>Since 1.2.0.</td>
         </tr>

         <tr>
           <td>
             <em>session_consistency</em>
           </td>
           <td>
            <p class="para">
              Request session consistency (read your writes). Allows use of all masters
              and all slaves which are in sync with the master.
              If no further parameters are given slaves are filtered out
              as there is no reliable way to test if a slave has caught up
              to the master or is lagging behind. Please note, if a filter chain
              generates an empty slave list and the PHP configuration directive
              <em>mysqlnd_ms.multi_master=0</em> is used, the plugin may
              emit a warning.
            </p>
            <p class="para">
             Session consistency temporarily requested using
             <span class="function"><a href="function.mysqlnd-ms-set-qos.html" class="function">mysqlnd_ms_set_qos()</a></span> is a valuable alternative
             to using <em>master_on_write</em>.
             <em>master_on_write</em> is likely to send more statements
             to the master than needed. The application may be able to continue
             operation at a lower consistency level after it has done
             some critical reads.
            </p>
          </td>
          <td>Since 1.1.0.</td>
         </tr>

         <tr>
           <td>
             <em>strong_consistency</em>
           </td>
           <td>
            <p class="para">
              Request strong consistency. Only masters will be used.
            </p>
          </td>
          <td>Since 1.2.0.</td>
         </tr>

        </tbody>
       
      </table>

     </dd>

    
    
     <dt id="ini.mysqlnd-ms-plugin-config-v2.failover">
      <em><code class="parameter">failover</code></em>
      Up to and including 1.3.x: <span class="type"><a href="language.types.string.html" class="type string">string</a></span>.
      Since 1.4.0: <span class="type"><a href="language.types.object.html" class="type object">object</a></span>.
     </dt>

     <dd>

      <p class="para">
       Failover policy. Supported policies:
       <em>disabled</em> (default), <em>master</em>,
       <em>loop_before_master</em> (Since 1.4.0).
      </p>
      <p class="para">
       If no failover policy is set, the plugin will not do any
       automatic failover (<em>failover=disabled</em>). Whenever
       the plugin fails to connect a server it will emit a warning and
       set the connections error code and message. Thereafter it is up to
       the application to handle the error and, for example, resent the
       last statement to trigger the selection of another server.
      </p>
      <p class="para">
       Please note, the automatic failover logic is applied when opening
       connections only. Once a connection has been opened no automatic attempts
       are made to reopen it in case of an error. If, for example, the server
       a connection is connected to is shut down and the  user attempts to
       run a statement on the connection, no automatic failover
       will be tried. Instead, an error will be reported.
      </p>
      <p class="para">
       If using <em>failover=master</em> the plugin will implicitly
       failover to a master, if available. Please check the
       concepts documentation to learn about potential
       pitfalls and risks of using <em>failover=master</em>.
      </p>
      <p class="para">
       <div class="example" id="example-1796">
        <p><strong>Example #22 Optional master failover when failing to connect to slave (PECL/mysqlnd_ms &lt; 1.4.0)</strong></p>
        <div class="example-contents">
<div class="inicode"><pre class="inicode">{
    &quot;myapp&quot;: {
        &quot;master&quot;: {
            &quot;master_0&quot;: {
                &quot;host&quot;: &quot;localhost&quot;
            }
        },
        &quot;slave&quot;: {
            &quot;slave_0&quot;: {
                &quot;host&quot;: &quot;192.168.78.136&quot;,
                &quot;port&quot;: &quot;3306&quot;
            }
        },
        &quot;failover&quot;: &quot;master&quot;
    }
}</pre>
</div>
        </div>

       </div>
      </p>
      <p class="para">
       Since PECL/mysqlnd_ms 1.4.0 the failover configuration keyword refers to an
       object.
      </p>
      <p class="para">
       <div class="example" id="example-1797">
        <p><strong>Example #23 New syntax since 1.4.0</strong></p>
        <div class="example-contents">
<div class="inicode"><pre class="inicode">{
    &quot;myapp&quot;: {
        &quot;master&quot;: {
            &quot;master_0&quot;: {
                &quot;host&quot;: &quot;localhost&quot;
            }
        },
        &quot;slave&quot;: {
            &quot;slave_0&quot;: {
                &quot;host&quot;: &quot;192.168.78.136&quot;,
                &quot;port&quot;: &quot;3306&quot;
            }
        },
        &quot;failover&quot;: {&quot;strategy&quot;: &quot;master&quot; }
    }
}</pre>
</div>
        </div>

       </div>
      </p>
      <table class="doctable informaltable">
       
        <col width="1*" />
        <col width="7*" />
        <col width="2*" />
        <thead>
         <tr>
          <th>Keyword</th>
          <th>Description</th>
          <th>Version</th>
         </tr>

        </thead>

        <tbody class="tbody">
         <tr>
          <td>
           <em>strategy</em>
          </td>
          <td>
           <p class="para">
            Failover policy. Possible values:
            <em>disabled</em> (default), <em>master</em>,
            <em>loop_before_master</em>
           </p>
           <p class="para">
            A value of <em>disabled</em> disables automatic failover.
           </p>
           <p class="para">
            Setting <em>master</em> instructs the plugin to try
            to connect to a master in case of a slave connection error. If the
            master connection attempt fails, the plugin exists the failover
            loop and returns an error to the user.
           </p>
           <p class="para">
             If using <em>loop_before_master</em> and a slave request
             is made, the plugin tries to connect to other slaves before failing
             over to a master. If multiple master are given and multi master is enabled,
             the plugin also loops over the list of masters and attempts to connect
             before returning an error to the user.
           </p>
          </td>
          <td>Since 1.4.0.</td>
         </tr>

         <tr>
          <td>
           <em>remember_failed</em>
          </td>
          <td>
           <p class="para">
            Remember failures for the duration of a web request. Default:
             <em>false</em>.
            </p>
            <p class="para">
             If set to <em>true</em> the plugin will remember failed
             hosts and skip the hosts in all future load balancing made for
             the duration of the current web request.
            </p>
          </td>
          <td>
           Since 1.4.0. The feature is only available together
           with the <em>random</em> and <em>roundrobin</em>
           load balancing filter. Use of the setting is recommended.
          </td>
         </tr>

         <tr>
           <td>
            <em>max_retries</em>
           </td>
           <td>
            <p class="para">
             Maximum number of connection attempts before skipping host.
             Default: <em>0</em> (no limit).
            </p>
            <p class="para">
             The setting is used to prevent hosts from being dropped of the
             host list upon the first failure. If set to <em>n &gt; 0</em>,
             the plugin will keep the node in the node list even after a failed
             connection attempt. The node will not be removed immediately from the slave respectively
             master lists after the first connection failure but instead be tried to
             connect to up to <em>n</em> times in future load balancing rounds
             before being removed.
            </p>
          </td>
          <td>
           Since 1.4.0. The feature is only available together
           with the <em>random</em> and <em>roundrobin</em>
           load balancing filter.
          </td>
         </tr>

        </tbody>
       
      </table>

      <p class="para">
       Setting <em>failover</em> to any other value but
       <em>disabled</em>, <em>master</em> or
       <em>loop_before_master</em>
       will not emit any warning or error.
      </p>
     </dd>

    
    
     <dt id="ini.mysqlnd-ms-plugin-config-v2.lazy-connections">
      <em><code class="parameter">lazy_connections</code></em>
      <span class="type"><a href="language.types.boolean.html" class="type bool">bool</a></span>
     </dt>

     <dd>

      <p class="para">
       Controls the use of lazy connections. Lazy connections
       are connections which are not opened before the client sends the first
       connection. Lazy connections are a default.
      </p>
      <p class="para">
       It is strongly recommended to use lazy connections.
       Lazy connections help to keep the number of open connections low.
       If you disable lazy connections and, for example, configure one MySQL
       replication master server and two MySQL replication slaves, the
       plugin will open three connections upon the first call to a
       connect function although the application might use the master
       connection only.
      </p>
      <p class="para">
       Lazy connections bare a risk if you make heavy use of actions
       which change the state of a connection. The plugin does not dispatch
       all state changing actions to all connections from the connection pool.
       The few dispatched actions are applied to already opened connections
       only. Lazy connections opened in the future are not affected.
       Only some settings are &quot;remembered&quot; and applied when lazy
       connections are opened.
      </p>
      <p class="para">
       <div class="example" id="example-1798">
        <p><strong>Example #24 Disabling lazy connection</strong></p>
        <div class="example-contents">
<div class="inicode"><pre class="inicode">{
    &quot;myapp&quot;: {
        &quot;master&quot;: {
            &quot;master_0&quot;: {
                &quot;host&quot;: &quot;localhost&quot;
            }
        },
        &quot;slave&quot;: {
            &quot;slave_0&quot;: {
                &quot;host&quot;: &quot;192.168.78.136&quot;,
                &quot;port&quot;: &quot;3306&quot;
            }
        },
        &quot;lazy_connections&quot;: 0
    }
}</pre>
</div>
        </div>

       </div>
      </p>
      <p class="para">
       Please, see also <em>server_charset</em> to overcome potential
       problems with string escaping and servers using different default
       charsets.
      </p>
     </dd>

    
    
     <dt id="ini.mysqlnd-ms-plugin-config-v2.server-charset">
      <em><code class="parameter">server_charset</code></em>
      <span class="type"><a href="language.types.string.html" class="type string">string</a></span>
     </dt>

     <dd>

      <p class="para">
       The setting has been introduced in 1.4.0. It is recommended to set it
       if using lazy connections.
      </p>
      <p class="para">
       The <em>server_charset</em> setting serves two purposes. It
       acts as a fallback charset to be used for string escaping done before
       a connection has been established and it helps to avoid escaping pitfalls
       in heterogeneous environments which servers using different default charsets.
      </p>
      <p class="para">
       String escaping takes a connections charset into account. String escaping
       is not possible before a connection has been opened and the connections
       charset is known. The use of lazy connections delays the actual opening
       of connections until a statement is send.
      </p>
      <p class="para">
       An application using lazy connections may attempt to escape a string
       before sending a statement. In fact, this should be a common case as
       the statement string may contain the string that is to be escaped.
       However, due to the lazy connection feature no connection has been opened
       yet and escaping fails. The plugin may report an error of the type
       <em>E_WARNING</em> and a message like <em>(mysqlnd_ms)
       string escaping doesn&#039;t work without established connection.
       Possible solution is to add server_charset to your configuration</em>
       to inform you of the pitfall.
      </p>
      <p class="para">
       Setting <em>server_charset</em> makes the plugin use
       the given charset for string escaping done on lazy connection handles
       before establishing a network connection to MySQL. Furthermore, the
       plugin will enforce the use of the charset when the connection is
       established.
      </p>
      <p class="para">
       Enforcing the use of the configured charset used for escaping is done
       to prevent tapping into the pitfall of using a different charset for
       escaping than used later for the connection. This has the additional
       benefit of removing the need to align the charset configuration of all
       servers used. No matter what the default charset on any of the servers is,
       the plugin will set the configured one as a default.
      </p>
      <p class="para">
       The plugin does not stop the user from changing the charset at any time
       using the <span class="function"><strong>set_charset()</strong></span> call or corresponding SQL statements.
       Please, note that the use of SQL is not recommended as it cannot be monitored
       by the plugin. The user can, for example, change the charset on a
       lazy connection handle after escaping a string and before the actual connection
       is opened. The charset set by the user will be used for any subsequent escaping
       before the connection is established. The connection will be established
       using the configured charset, no matter what the server charset is or
       what the user has set before. Once a connection has been opened,
       <em>set_charset</em> is of no meaning anymore.
      </p>
      <p class="para">
       <div class="example" id="example-1799">
        <p><strong>Example #25 String escaping on a lazy connection handle</strong></p>
        <div class="example-contents">
<div class="inicode"><pre class="inicode">{
    &quot;myapp&quot;: {
        &quot;master&quot;: {
            &quot;master_0&quot;: {
                &quot;host&quot;: &quot;localhost&quot;
            }
        },
        &quot;slave&quot;: {
            &quot;slave_0&quot;: {
                &quot;host&quot;: &quot;192.168.78.136&quot;,
                &quot;port&quot;: &quot;3306&quot;
            }
        },
        &quot;lazy_connections&quot;: 1,
        &quot;server_charset&quot; : &quot;utf8&quot;
    }
}</pre>
</div>
        </div>

        <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br />$mysqli&nbsp;</span><span style="color: #007700">=&nbsp;new&nbsp;</span><span style="color: #0000BB">mysqli</span><span style="color: #007700">(</span><span style="color: #DD0000">"myapp"</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">"username"</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">"password"</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">"database"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">real_escape</span><span style="color: #007700">(</span><span style="color: #DD0000">"this&nbsp;will&nbsp;be&nbsp;escaped&nbsp;using&nbsp;the&nbsp;server_charset&nbsp;setting&nbsp;-&nbsp;utf8"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">set_charset</span><span style="color: #007700">(</span><span style="color: #DD0000">"latin1"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">real_escape</span><span style="color: #007700">(</span><span style="color: #DD0000">"this&nbsp;will&nbsp;be&nbsp;escaped&nbsp;using&nbsp;latin1"</span><span style="color: #007700">);<br /></span><span style="color: #FF8000">/*&nbsp;server_charset&nbsp;implicitly&nbsp;set&nbsp;-&nbsp;utf8&nbsp;connection&nbsp;*/<br /></span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">query</span><span style="color: #007700">(</span><span style="color: #DD0000">"SELECT&nbsp;'This&nbsp;connection&nbsp;will&nbsp;be&nbsp;set&nbsp;to&nbsp;server_charset&nbsp;upon&nbsp;establishing'&nbsp;AS&nbsp;_msg&nbsp;FROM&nbsp;DUAL"</span><span style="color: #007700">);<br /></span><span style="color: #FF8000">/*&nbsp;latin1&nbsp;used&nbsp;from&nbsp;now&nbsp;on&nbsp;*/<br /></span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">set_charset</span><span style="color: #007700">(</span><span style="color: #DD0000">"latin1"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
         </div>

       </div>
      </p>
     </dd>

    
    
     <dt id="ini.mysqlnd-ms-plugin-config-v2.master-on-write">
      <em><code class="parameter">master_on_write</code></em>
      <span class="type"><a href="language.types.boolean.html" class="type bool">bool</a></span>
     </dt>

     <dd>

      <p class="para">
       If set, the plugin will use the master server only after the
       first statement has been executed on the master. Applications
       can still send statements to the slaves using SQL hints to
       overrule the automatic decision.
      </p>
      <p class="para">
       The setting may help with replication lag. If an application runs
       an <em>INSERT</em> the plugin will, by default, use the
       master to execute all following statements, including
       <em>SELECT</em> statements. This helps to avoid problems
       with reads from slaves which have not replicated the
       <em>INSERT</em> yet.
      </p>
      <p class="para">
       <div class="example" id="example-1800">
        <p><strong>Example #26 Master on write for consistent reads</strong></p>
        <div class="example-contents">
<div class="inicode"><pre class="inicode">{
    &quot;myapp&quot;: {
        &quot;master&quot;: {
            &quot;master_0&quot;: {
                &quot;host&quot;: &quot;localhost&quot;
            }
        },
        &quot;slave&quot;: {
            &quot;slave_0&quot;: {
                &quot;host&quot;: &quot;192.168.78.136&quot;,
                &quot;port&quot;: &quot;3306&quot;
            }
        },
        &quot;master_on_write&quot;: 1
    }
}</pre>
</div>
        </div>

       </div>
      </p>
      <p class="para">
       Please, note the <em>quality_of_service</em> filter introduced
       in version 1.2.0-alpha. It gives finer control, for example, for achieving read-your-writes
       and, it offers additional functionality introducing
       <a href="mysqlnd-ms.qos-consistency.html" class="link">service levels</a>.
      </p>
      <p class="para">
       All <a href="mysqlnd-ms.plugin-ini-json.html#ini.mysqlnd-ms-plugin-config-v2.trx-stickiness" class="link">transaction stickiness</a> settings,
       including <em>trx_stickiness=on</em>, are overruled by <em>master_on_write=1</em>.
      </p>
     </dd>

    
    
     <dt id="ini.mysqlnd-ms-plugin-config-v2.trx-stickiness">
      <em><code class="parameter">trx_stickiness</code></em>
      <span class="type"><a href="language.types.string.html" class="type string">string</a></span>
     </dt>

     <dd>

      <p class="para">
       Transaction stickiness policy. Supported policies:
       <em>disabled</em> (default), <em>master</em>.
      </p>
      <p class="para">
       The setting requires 5.4.0 or newer. If used with PHP older than 5.4.0,
       the plugin will emit a warning like
       <em>(mysqlnd_ms) trx_stickiness strategy is not supported before PHP 5.3.99</em>.
      </p>
      <p class="para">
       If no transaction stickiness policy is set or,
       if setting <em>trx_stickiness=disabled</em>,
       the plugin is not transaction aware. Thus, the plugin may load balance
       connections and switch connections in the middle of a transaction.
       The plugin is not transaction safe. SQL hints must be used
       avoid connection switches during a transaction.
      </p>
      <p class="para">
       As of PHP 5.4.0 the mysqlnd library allows the plugin to monitor
       the <em>autocommit</em> mode set by calls to the
       libraries <em>set_autocommit()</em> function.
       If setting <em>set_stickiness=master</em> and
       <em>autocommit</em> gets disabled by a PHP MySQL extension
       invoking the <em>mysqlnd</em> library internal
       function call <em>set_autocommit()</em>, the plugin is made
       aware of the begin of a transaction. Then, the plugin stops load balancing
       and directs all statements to the master server until
       <em>autocommit</em> is enabled. Thus, no SQL hints are required.
      </p>
      <p class="para">
       An example of a PHP MySQL API function calling the <em>mysqlnd</em>
       library internal function call <em>set_autocommit()</em> is
       <span class="function"><a href="mysqli.autocommit.html" class="function">mysqli_autocommit()</a></span>.
      </p>
      <p class="para">
       Although setting <em>trx_stickiness=master</em>, the plugin
       cannot be made aware of <em>autocommit</em> mode changes caused
       by SQL statements such as <em>SET AUTOCOMMIT=0</em> or <em>BEGIN</em>.
      </p>
      <p class="para">
       As of PHP 5.5.0, the mysqlnd library features additional C API calls to
       control transactions. The level of control matches the one offered by SQL
       statements. The <em>mysqli</em> API has been modified to use
       these calls. Since version 1.5.0, PECL/mysqlnd_ms can monitor not only
       <span class="function"><a href="mysqli.autocommit.html" class="function">mysqli_autocommit()</a></span>, but also <span class="function"><strong>mysqli_begin()</strong></span>,
       <span class="function"><a href="mysqli.commit.html" class="function">mysqli_commit()</a></span> and <span class="function"><a href="mysqli.rollback.html" class="function">mysqli_rollback()</a></span> to
       detect transaction boundaries and stop load balancing for the duration of
       a transaction.
      </p>
      <p class="para">
       <div class="example" id="example-1801">
        <p><strong>Example #27 Using master to execute transactions</strong></p>
        <div class="example-contents">
<div class="inicode"><pre class="inicode">{
    &quot;myapp&quot;: {
        &quot;master&quot;: {
            &quot;master_0&quot;: {
                &quot;host&quot;: &quot;localhost&quot;
            }
        },
        &quot;slave&quot;: {
            &quot;slave_0&quot;: {
                &quot;host&quot;: &quot;192.168.78.136&quot;,
                &quot;port&quot;: &quot;3306&quot;
            }
        },
        &quot;trx_stickiness&quot;: &quot;master&quot;
    }
}</pre>
</div>
        </div>

       </div>
      </p>
      <p class="para">
       Since version 1.5.0 automatic and silent failover is disabled for the
       duration of a transaction. If the boundaries of a transaction have been
       properly detected, transaction stickiness is enabled and a server fails,
       the plugin will not attempt to fail over to the next server, if any, regardless
       of the failover policy configured. The user must handle the error
       manually. Depending on the configuration, the plugin may emit
       an error of type <em>E_WARNING</em> reading like
       <em>(mysqlnd_ms) Automatic failover is not permitted in the middle of a transaction</em>.
       This error may then be overwritten by follow up errors such as
       <em>(mysqlnd_ms) No connection selected by the last filter</em>.
       Those errors will be generated by the failing query function.
      </p>
      <p class="para">
       <div class="example" id="example-1802">
        <p><strong>Example #28 No automatic failover, error handling pitfall</strong></p>
        <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br /></span><span style="color: #FF8000">/*&nbsp;assumption:&nbsp;automatic&nbsp;failover&nbsp;configured&nbsp;*/<br /></span><span style="color: #0000BB">$mysqli&nbsp;</span><span style="color: #007700">=&nbsp;new&nbsp;</span><span style="color: #0000BB">mysqli</span><span style="color: #007700">(</span><span style="color: #DD0000">"myapp"</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">"username"</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">"password"</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">"database"</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">/*&nbsp;sets&nbsp;plugin&nbsp;internal&nbsp;state&nbsp;in_trx&nbsp;=&nbsp;1&nbsp;*/<br /></span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">autocommit</span><span style="color: #007700">(</span><span style="color: #0000BB">false</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">/*&nbsp;assumption:&nbsp;server&nbsp;fails&nbsp;*/<br /></span><span style="color: #007700">if&nbsp;(!(</span><span style="color: #0000BB">$res&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">query</span><span style="color: #007700">(</span><span style="color: #DD0000">"SELECT&nbsp;'Assume&nbsp;this&nbsp;query&nbsp;fails'&nbsp;AS&nbsp;_msg&nbsp;FROM&nbsp;DUAL"</span><span style="color: #007700">)))&nbsp;{<br />&nbsp;</span><span style="color: #FF8000">/*&nbsp;handle&nbsp;failure&nbsp;of&nbsp;transaction,&nbsp;plugin&nbsp;internal&nbsp;state&nbsp;is&nbsp;still&nbsp;in_trx&nbsp;=&nbsp;1&nbsp;*/<br />&nbsp;</span><span style="color: #0000BB">printf</span><span style="color: #007700">(</span><span style="color: #DD0000">"[%d]&nbsp;%s"</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">errno</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">error</span><span style="color: #007700">);<br />&nbsp;</span><span style="color: #FF8000">/*<br />&nbsp;&nbsp;If&nbsp;using&nbsp;autocommit()&nbsp;based&nbsp;transaction&nbsp;detection&nbsp;it&nbsp;is&nbsp;a<br />&nbsp;&nbsp;MUST&nbsp;to&nbsp;call&nbsp;autocommit(true).&nbsp;Otherwise&nbsp;the&nbsp;plugin&nbsp;assumes<br />&nbsp;&nbsp;the&nbsp;current&nbsp;transaction&nbsp;continues&nbsp;and&nbsp;connection<br />&nbsp;&nbsp;changes&nbsp;remain&nbsp;forbidden.<br />&nbsp;*/<br />&nbsp;</span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">autocommit</span><span style="color: #007700">(</span><span style="color: #0000BB">true</span><span style="color: #007700">);<br />&nbsp;</span><span style="color: #FF8000">/*&nbsp;Likewise,&nbsp;you'll&nbsp;want&nbsp;to&nbsp;start&nbsp;a&nbsp;new&nbsp;transaction&nbsp;*/<br />&nbsp;</span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">autocommit</span><span style="color: #007700">(</span><span style="color: #0000BB">false</span><span style="color: #007700">);<br />}<br /></span><span style="color: #FF8000">/*&nbsp;latin1&nbsp;used&nbsp;from&nbsp;now&nbsp;on&nbsp;*/<br /></span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">set_charset</span><span style="color: #007700">(</span><span style="color: #DD0000">"latin1"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
         </div>

       </div>
      </p>
      <p class="para">
       If a server fails in the middle of a transaction the
       plugin continues to refuse to switch connections until the
       current transaction has been finished. Recall
       that the plugin monitors API calls to detect transaction
       boundaries. Thus, you have to, for example, enable
       auto commit mode to end the current transaction before
       the plugin continues load balancing and switches the server.
       Likewise, you will want to start a new transaction
       immediately thereafter and disable auto commit mode again.
      </p>
      <p class="para">
       Not handling failed queries and not ending a failed transaction
       using API calls may cause all following commands emit errors
       such as  <em>Commands out of sync; you can&#039;t run this command now</em>.
       Thus, it is important to handle all errors.
      </p>
     </dd>

    

    
     <dt id="ini.mysqlnd-ms-plugin-config-v2.transient_error">
       <em><code class="parameter">transient_error</code></em>
       <span class="type"><a href="language.types.object.html" class="type object">object</a></span>
     </dt>

     <dd>

      <p class="para">
       The setting has been introduced in 1.6.0.
      </p>
      <p class="para">
       A database cluster node may reply a transient error to a client. The client
       can then repeat the operation on the same node, fail over to a different node
       or abort the operation. Per definition is it safe for a client to
       retry the same operation on the same node before giving up.
      </p>
      <p class="para">
       <em>PECL/mysqlnd_ms</em> can perform the retry
       loop on behalf of the application.
       By configuring <em>transient_error</em> the plugin can be
       instructed to repeat operations failing with a certain error code for
       a certain maximum number of times with a pause between the retries.
       If the transient error disappears during loop execution, it is
       hidden from the application. Otherwise, the error is
       forwarded to the application by the end of the loop.
      </p>
      <p class="para">
       <div class="example" id="example-1803">
        <p><strong>Example #29 Retry loop for transient errors</strong></p>
        <div class="example-contents">
<div class="inicode"><pre class="inicode">{
    &quot;myapp&quot;: {
        &quot;master&quot;: {
            &quot;master_0&quot;: {
                &quot;host&quot;: &quot;localhost&quot;
            }
        },
        &quot;slave&quot;: {
            &quot;slave_0&quot;: {
                &quot;host&quot;: &quot;192.168.78.136&quot;,
                &quot;port&quot;: &quot;3306&quot;
            }
       },
       &quot;transient_error&quot;: {
          &quot;mysql_error_codes&quot;: [
            1297
          ],
          &quot;max_retries&quot;: 2,
          &quot;usleep_retry&quot;: 100
       }
    }
}</pre>
</div>
        </div>

      </div>
     </p>
      <table class="doctable informaltable">
       
        <col width="1*" />
        <col width="7*" />
        <col width="2*" />
        <thead>
         <tr>
          <th>Keyword</th>
          <th>Description</th>
          <th>Version</th>
         </tr>

        </thead>

        <tbody class="tbody">
         <tr>
          <td>
           <em>mysql_error_codes</em>
          </td>
          <td>
           <p class="para">
            List of transient error codes. You may add any MySQL error code
            to the list. It is possible to consider any error as transient
            not only <em>1297</em>
            (<em>HY000 (ER_GET_TEMPORARY_ERRMSG),
            Message: Got temporary error %d &#039;%s&#039; from %s</em>).
            Before adding other codes but <em>1297</em> to the list,
            make sure your cluster supports a new attempt without impacting
            the state of your application.
           </p>
          </td>
          <td>Since 1.6.0.</td>
         </tr>

         <tr>
          <td>
           <em>max_retries</em>
          </td>
          <td>
           <p class="para">
            How often to retry an operation which
            fails with a transient error before forwarding the
            failure to the user.
           </p>
           <p class="para">
             Default: <em>1</em>
           </p>
          </td>
          <td>Since 1.6.0.</td>
         </tr>

         <tr>
          <td>
           <em>usleep_retry</em>
          </td>
          <td>
           <p class="para">
            Milliseconds to sleep between transient error retries.
            The value is passed to the C function <span class="function"><a href="function.usleep.html" class="function">usleep()</a></span>,
            hence the name.
           </p>
           <p class="para">
             Default: <em>100</em>
           </p>
          </td>
          <td>Since 1.6.0.</td>
         </tr>

        </tbody>
       
      </table>

     </dd>

    

   </dl>

  </p>

</div><hr /><div class="manualnavbar" style="text-align: center;">
 <div class="prev" style="text-align: left; float: left;"><a href="mysqlnd-ms.configuration.html">运行时配置</a></div>
 <div class="next" style="text-align: right; float: right;"><a href="mysqlnd-ms.plugin-ini-v1.html">Plugin configuration file (&lt;= 1.0.x)</a></div>
 <div class="up"><a href="mysqlnd-ms.setup.html">安装／配置</a></div>
 <div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
